<html>
<head><meta charset="utf-8"><title>experience report · wg-async-foundations/book · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/index.html">wg-async-foundations/book</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html">experience report</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="173224412"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173224412" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173224412">(Aug 14 2019 at 17:33)</a>:</h4>
<p>so I had a good conversation <span class="user-mention" data-user-id="235180">@Jack Moffitt</span> recently, who was telling me of their difficulties getting started with the async book</p>



<a name="173224488"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173224488" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173224488">(Aug 14 2019 at 17:34)</a>:</h4>
<p>it seemed like a lot of it stemmed from (a) it being hard and confusing to figure out which versions of everything to be using; (b) the hello world examples don't spell out enough stuff like "which feature gate to use" and which version of futures crate; (c) the futures crate itself that is most prominently on <a href="http://docs.rs" target="_blank" title="http://docs.rs">docs.rs</a> is 0.1.28 which includes its own version of Future and doesn't have many of the fns that appear in the book</p>



<a name="173224529"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173224529" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173224529">(Aug 14 2019 at 17:35)</a>:</h4>
<p>anyway I asked them to come and jot some notes here</p>



<a name="173225278"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173225278" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173225278">(Aug 14 2019 at 17:46)</a>:</h4>
<p>sounds like useful feedback! I'm excited to hear more</p>



<a name="173225938"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173225938" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> nikomatsakis <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173225938">(Aug 14 2019 at 17:55)</a>:</h4>
<p>I think <a href="https://internals.rust-lang.org/t/async-await-ecosystem-experience-report/10707" target="_blank" title="https://internals.rust-lang.org/t/async-await-ecosystem-experience-report/10707">this message from internals</a> perhaps captures the "essence" of <span class="user-mention" data-user-id="235180">@Jack Moffitt</span>'s experience, if not the details.</p>



<a name="173227413"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173227413" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173227413">(Aug 14 2019 at 18:10)</a>:</h4>
<blockquote>
<p>I still remain excited about async in rust, but feel like I need to wait a few more months for the ecosystem to continue to build out and up </p>
</blockquote>
<p>sounds like a reasonable summary to me</p>



<a name="173227459"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173227459" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173227459">(Aug 14 2019 at 18:10)</a>:</h4>
<p>I wouldn't expect anything different</p>



<a name="173227479"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173227479" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173227479">(Aug 14 2019 at 18:10)</a>:</h4>
<p>but I am interested to know about details of the book that could've helped in the problem-solving</p>



<a name="173227694"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173227694" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jack Moffitt <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173227694">(Aug 14 2019 at 18:12)</a>:</h4>
<p>That internals message is indeed, similar, but he made it farther than I did.</p>
<p>My experience started with a teammate reporting a strange compiler error. Specifically there was a function that returned <code>impl Future&lt;Output = ()&gt;</code> and he was trying to return <code>future::ok::&lt;(),()&gt;(())</code>. I first looked at the docs, which I found via Google. They showed that future::ok returned FutureResult and that FutureResult impled Future, so the code looked fine, even though it wouldn't compile. It was clear after a bit of digging that these were outdated or perhaps newer docs.</p>
<p>Next I decided I'd mock this up on the playground and see what happened, but I couldn't get anything to compile. That wasn't too surprising, since I hadn't written any async code before in Rust. I then went to the async book and decided I'd just start from the beginning until I got something simple working, which I could then progress to a simplified example of the future::ok thing.</p>
<p>Here I got stuck because executor::block_on didn't exist, and nothing I did seemed to help. I started trying to figure out which version of futures i needed, whether I needed tokio or not, etc. And there I stopped for the evening.</p>



<a name="173228090"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228090" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jack Moffitt <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228090">(Aug 14 2019 at 18:17)</a>:</h4>
<blockquote>
<p>but I am interested to know about details of the book that could've helped in the problem-solving</p>
</blockquote>
<p>One thing is that none of the examples run in the playground. They give approximately the same errors I was getting, which makes it seem like the book is out of date. Fixing that will help.</p>
<p>I also think having some kind of Chapter 0 that addresses this transition period would be helpful. Here's what you need to try this out now, and here are the major libs involved and their current state. And keep that page as up to date as possible. Part of my problem is there is no foothold to start to build my knowledge base. I know only that a) std:<span aria-label="future" class="emoji emoji-1f52e" role="img" title="future">:future:</span>:Future is stable, async and .await will soon be stable (and are currently supported in nightly), and beyond that I have no idea which libraries will be needed/useful and the difference between the state right now and the desired end state.</p>
<p>It appears I need to be using futures-preview, feature(async_await), and aside from toy examples, some runtime like the runtime crate or tokio.</p>



<a name="173228242"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228242" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228242">(Aug 14 2019 at 18:19)</a>:</h4>
<blockquote>
<p>One thing is that none of the examples run in the playground. They give approximately the same errors I was getting, which makes it seem like the book is out of date. Fixing that will help.</p>
</blockquote>
<p>The book isn't out of date-- it seems like you weren't using the correct version of hte <code>futures-preview</code> crate</p>



<a name="173228249"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228249" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228249">(Aug 14 2019 at 18:19)</a>:</h4>
<p>or weren't using <code>futures-preview</code> at all</p>



<a name="173228265"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228265" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228265">(Aug 14 2019 at 18:19)</a>:</h4>
<p>the examples cannot be made to work on the playground because the playground does not include <code>futures-preview</code></p>



<a name="173228297"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228297" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jack Moffitt <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228297">(Aug 14 2019 at 18:19)</a>:</h4>
<p>I wasn't using it at all, which is part of hte problem. Where was I supposed to learn about this? I realize now I can get to the book's example code repo and see it there, but the book doesn't talk about this.</p>



<a name="173228379"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228379" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228379">(Aug 14 2019 at 18:20)</a>:</h4>
<p>in the very first example there is a sample of what your cargo.toml should look like: <a href="https://rust-lang.github.io/async-book/01_getting_started/05_http_server_example.html" target="_blank" title="https://rust-lang.github.io/async-book/01_getting_started/05_http_server_example.html">https://rust-lang.github.io/async-book/01_getting_started/05_http_server_example.html</a></p>



<a name="173228403"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228403" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228403">(Aug 14 2019 at 18:20)</a>:</h4>
<p>It also describes how to get the proper version of rustc using <code>rustup</code></p>



<a name="173228427"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228427" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228427">(Aug 14 2019 at 18:21)</a>:</h4>
<p>Is there another way this could have been communicated more clearly?</p>



<a name="173228714"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228714" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228714">(Aug 14 2019 at 18:24)</a>:</h4>
<p>(all the "applied" sections have similar Cargo.toml samples)</p>



<a name="173228717"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228717" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jack Moffitt <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228717">(Aug 14 2019 at 18:24)</a>:</h4>
<p>I gave up on the page before that one, that had the hello world example I couldn't get to work. <a href="https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html" target="_blank" title="https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html">https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html</a></p>
<p>I see there is a "State of Asynchronous Rust" page already there, but it is written as if I know what lots of these things are and does not mention futures-preview.</p>



<a name="173228791"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173228791" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173228791">(Aug 14 2019 at 18:25)</a>:</h4>
<p>Okay. Those were only intended as examples and not as runnable code, but it seems like that was confusing so perhaps that section should be amended to include a Cargo.toml as well</p>



<a name="173229207"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173229207" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jack Moffitt <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173229207">(Aug 14 2019 at 18:30)</a>:</h4>
<p>My suggestion is perhaps reordering that stuff a bit. Make a Chapter 0 which is "The State of Asynchronous Rust". Spurce that up a bit so it's more newbie friendly. Describe the major players, the desired end state (as it is understood right now), and the current state. Then show exactly what's needed to get the stuff from the book to work, that is necessary now but wouldn't necessarily be needed in the future.</p>
<p>Can we turn off run buttons and such until those will work? Can we update playground to work with the ideal current state?</p>
<p>Maybe we can make a special note on each page pointing back at chapter 0 saying "Asynchronous Rust is in active development, and is not yet done. If you have any trouble with the examples here, please make sure you read or re-read  Chapter 0 which describes how to use async Rust during this transition period."</p>



<a name="173229768"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173229768" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173229768">(Aug 14 2019 at 18:36)</a>:</h4>
<p>There's an open issue about the run buttons. I don't have a way to control that that I know of, but it is worthy of investigation. I also don't have a way to control which crates appear in the playground, and I don't think it would be correct for the playground to start using futures 0.3 anyways until async/await is stable</p>



<a name="173229792"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173229792" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173229792">(Aug 14 2019 at 18:36)</a>:</h4>
<p>once async/await staabilizes and futures-preview is released as futures 0.3, that problem will solve itself</p>



<a name="173229851"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173229851" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jack Moffitt <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173229851">(Aug 14 2019 at 18:37)</a>:</h4>
<p>If you think that could work, I can try drafting a PR. I'm happy to pitch in here.</p>



<a name="173230148"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173230148" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173230148">(Aug 14 2019 at 18:41)</a>:</h4>
<blockquote>
<p>The State of Asynchronous Rust</p>
</blockquote>
<p>there already is a section under this name-- feel free to send PRs to add things to it if you think it's unclear</p>



<a name="173230219"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173230219" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173230219">(Aug 14 2019 at 18:42)</a>:</h4>
<p>in general feel free to open PRs or issues for any difficulties you're experiencing or ideas you have</p>



<a name="173230228"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/201246-wg-async-foundations/book/topic/experience%20report/near/173230228" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Taylor Cramer <a href="https://rust-lang.github.io/zulip_archive/stream/201246-wg-async-foundations/book/topic/experience.20report.html#173230228">(Aug 14 2019 at 18:42)</a>:</h4>
<p>and I'll do my best to respond in a timely manner</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>